package com.wsg.dep.seq;

import com.wsg.dep.core.Cursored;
import com.wsg.dep.core.SequenceBarrier;
import com.wsg.dep.core.event.DataProvider;
import com.wsg.dep.core.event.EventPoller;

/**
 * 协调声明序列以访问数据结构，同时跟踪依赖的{@link Sequence}
 */
public interface Sequencer extends Cursored, Sequenced
{
    /**
     * 序列号的初始有标志
     */
    long INITIAL_CURSOR_VALUE = -1L;

    /**
     * 用于声明一个特定的序列，通常在将环形缓冲区初始化为特定值时使用。传入的sequence参数表示要初始化到的序列值。
     *
     * @param sequence 序列号的初始值
     */
    void claim(long sequence);

    /**
     * 非阻塞地检查指定的序列是否已发布，并且对应的事件是否可供使用。
     *
     * @param sequence 待检查的序列号
     * @return 如果序列可用则返回true，否则返回false。
     */
    boolean isAvailable(long sequence);

    /**
     * 将指定的门控序列（gatingSequences）安全且原子地添加到Disruptor实例的门控序列列表中。门控序列用于控制对环形缓冲区的访问。
     *
     * @param gatingSequences 新增的序列
     */
    void addGatingSequences(Sequence... gatingSequences);

    /**
     * 从当前的Sequencer中移除指定的序列。
     *
     * @param sequence 删除的序列
     * @return 如果成功找到并移除序列，则返回true，否则返回false。
     */
    boolean removeGatingSequence(Sequence sequence);

    /**
     * 创建一个新的SequenceBarrier，
     * 供EventProcessor（事件处理器）使用，用于跟踪从环形缓冲区中哪些消息是可供读取的。
     *
     *
     * @param sequencesToTrack 传入的sequencesToTrack参数表示新创建的屏障将等待的所有序列。
     * @return 环形缓冲区中哪些消息是可供读取的
     * @see SequenceBarrier
     */
    SequenceBarrier newBarrier(Sequence... sequencesToTrack);

    /**
     * 获取添加到当前环形缓冲区的所有门控序列中的最小序列值。
     *
     * @return 如果没有添加任何序列，则返回当前的游标序列值。
     */
    long getMinimumSequence();

    /**
     * 获取可以安全地从环形缓冲区读取的最高序列编号。
     * 该方法会根据Sequencer的实现，在nextSequence和availableSequence之间进行扫描。
     * 如果没有大于等于nextSequence的可用值，则返回nextSequence - 1。
     * 消费者应传入比上一个成功处理的序列大 1 的值，以确保正确工作。
     *
     * @param nextSequence      扫描开始的序列号
     * @param availableSequence 扫描到此序列号结束
     * @return 如果没有大于等于nextSequence的可用值，则返回nextSequence - 1。
     */
    long getHighestPublishedSequence(long nextSequence, long availableSequence);

    /**
     * 这是一个泛型方法，用于创建一个新的EventPoller，该EventPoller基于给定的DataProvider和门控序列（gatingSequences）。
     * DataProvider提供数据，而门控序列用于控制对数据的访问。
     * @param provider
     * @param gatingSequences
     * @param <T>
     * @return
     */
    <T> EventPoller<T> newPoller(DataProvider<T> provider, Sequence... gatingSequences);
}